Over 1,000 Windows 95 Programs

home *** CD-ROM | disk | FTP | other *** search

/ Over 1,000 Windows 95 Programs / Over 1000 Windows 95 Programs (Microforum) (Disc 2).iso / 1445 / bestop.doc next >

Wrap

Text File | 1997-04-07 | 120.0 KB | 3,242 lines

1 - - - - - Program Documentation for BESTOP - - - - - - - - 0 - - - DATE PREPARED: FEBRUARY 1989 1 TABLE_OF_CONTENTS + _____ __ ________ 0I.__FOREWORD 1 +__ ________ 0II.__INTRODUCTION 2 +___ ____________ A. Background 2 B. Program Control 2 C. Data Constants And Work Areas 4 0III.__INSTRUCTION_SPECIFICATIONS 7 +____ ___________ ______________ A. Instructions 7 B. Conditional Instructions 8 1. IF (Character Field Comparison) 9 2. IF (Numeric Field Comparison) 10 3. IF (Multiple Comparison) 10 4. IF (character comparison) 11 5. IF (Control Break) 12 6. IF (Printer Line Test) 12 7. IF (Condition Test) 12 8. OTHERWISE 13 9. UNCONDITIONAL 13 C. Data Movement Instructions 14 1. MOVE 14 2. EDIT 14 3. CLEAR 15 D. Arithmetic Instrictions 15 1. ADD 15 2. SUBTRACT 16 3. MULTIPLY 16 4. DIVIDE 16 E. Output And Control Instructions 17 1. WRITE (Numbered Files and Punch File) 17 2. WRITE (Listing with Spaces) 18 3. WRITE (Listing with Skip to Numbered Line) 18 4. Write (Space Printer without Printing) 18 5. WRITE (Skip to Numbered Line without Printing) 18 6. GET 19 7. HALT 19 F. Soubroutine Linkage Instruction 19 1. SUBROUTINE 20 2. RETURN 20 3. BRANCH 20 G. Table Lookup Instructions 20 1. TABLE DEFINITION 21 2. TABLE ENTRY 21 3. LOOKUP 21 H. Matched File Control 22 1. MATCH KEYS 24 I. Advanced Techniques 24 1. FIND 24 2. MOVE (to displaced field) 25 3. MOVE (from displaced field) 26 4. DO AGAIN 27 0IV.__PROGRAMMING_TECHNIQUES 29 +___ ___________ __________ A. Routines 29 0 -i- 1 B. Subroutines 30 C. Tables 32 D. Matched Input Files 34 E. Page Format Control 36 F. Summarizing Data 38 0V.__PROGRAM_DEBUGGING 42 +__ _______ _________ A. Compilation Diagnostics 42 B. Instruction Diagnostics 42 D. Record Counts And File Dumps 44 E. Test Runs 45 0VI.__APPENDIX_A_-_OS/370_OPERATING_INSTRUCTIONS 46 +___ ________ _ _ ______ _________ ____________ A. Job Control Language 46 B. JOB Statement 46 C. EXEC Statement 46 D. STEPLIB Card 47 E. DD Statements 47 F. Completion Codes 48 G. External Tables 49 0VII.__APPENDIX_B_-_MAXIMUM_FIELD_SIZES 50 +____ ________ _ _ _______ _____ _____ 0VIII.__APPENDIX_C_-_EIA_IMPLEMENTATIONS_OF_BESTOP 51 +_____ ________ _ _ ___ _______________ __ ______ A. BESTOP50, BESTOPVL, BEST400 51 B. SUPERB 51 C. BESTOP 51 - - - - - - - - - - 0 -ii- 1 BESTOP ________________________________________________________________________ I.__FOREWORD + __ ________ 0 This document is a revised text originally written in November 1971 by the Office of Research and Statistics, Social Security Administration. This new documentation includes some new features and other enhancements. This program product has performed exceedingly well for a number of years at this istallation. But no guarantee is expressed or implied that this program will necessarily perform in accordance with the users specified needs. - - - - - - - - - - - - ________________________________________________________________________ -1- 1 BESTOP ________________________________________________________________________ II.__INTRODUCTION + ___ ____________ 0 A.__Background + __ __________ The original Business Economics Statistical Operations Program (BESTOP) was developed by the Office of Business Economics (OBE), U.S. Department of Commerce, in 1965. Since that time it has been extended both by OBE and by other organizations to whom the program has been made available. The BESTOP language is the principal one in use for applications programming in OBE and has been used extensively by several other agencies of the Federal Government. While there is no accurate estimate of the number of programs that have been written in BESTOP, it numbers in the tens of thousands in OBE alone. BESTOP was developed to meet a requirement for fast turnaround on a large number of relatively short jobs. It has been used successfully by programmers and non-programmers alike and is particularly effective in report writing, file maintenance, and similar applications. The BESTOP Compiler produces an executable program in memory from BESTOP source statements. Machine code is assembled in line as the statements are read. The program is executed when the last statement has been processed unless an error is detected in the program. The syntax of the BESTOP language permits the diagnosis of all syntactical errors during the translation process. Such errors are noted on a printed listing of the source statements and must be corrected before the program can be executed. A program that is syntactically correct is executed. A program that is syntactically correct is executed immediately and will not stop until all of the input records have been processed or a "HALT" instruction is executed in the program. The program will not normally "hang up" without a diagnostic message although some care must be taken to avoid program loops when writing subroutines. In addition to the compilation diagnostics, record counts and partial file dumps are produced as an aid to checking the results of a run. B.__Program_Control + __ _______ _______ A BESTOP program consists of a specialized record reading routine followed by an object program that is compiled from BESTOP instructions as shown in figure 1. In the execution of a program, control passes first to the record reading routine to read a record (or two records in the case of matched file operations), then to the object program, and then back to the reading routine. This cycle is repeated until the input file is exhausted or until a HALT instruction is executed in the object program. 0 ________________________________________________________________________ -2- 1 BESTOP ________________________________________________________________________ ________________ | Specialized | | Record | |------>| Reading | | | Routine | | |______________| | | | | | __________v__________ | | Object Program | |____| Produced from the | | Instructions Cards| |___________________| Figure 1. The flow of Control in a BESTOP Program Not all of the instructions will be executed during each pass through the object program. Conditional instructions permit the specification of tests that must be met before other processing instructions will be executed. Other non-executable instructions are provided for the creation of tables and subroutines. The program attempts to execute all of the processing instructions in each pass through the object program unless a GET instruction is executed. The GET instruction causes an immediate return to the record reading routine to get the next record and processing then resumes with the first instruction in the program. After the last input record has been processed, there is one "last pass" through the object program to execute any instructions that must be executed at the end of the run. Other instructions are not executed in the last pass. The record reading routine is automatic and is always performed by the record reading routine. The specific file(s) to be read is specified in a job control language parameter. If two files are to be read simultaneously, a special sequence key instruction must be included at the beginning of the program to provide routine. To write records, one or more WRITE instructions must be included in the object program. The WRITE instruction also provides vertical spacing control when printing. - - ________________________________________________________________________ -3- 1 BESTOP ________________________________________________________________________ C.__Data_Constants_And_Work_Areas + __ ____ _________ ___ ____ _____ All of the data that is processed by the object program must be contained in tables, instruction constants, or one of the work areas shown in figure 2. Work areas of appropriate size are always provided for input from the card reader and for data that is to be punched or printed. Additional areas may be used for tape or disk files. The length of each tape or disk area is equal to the length of the logical records in the corresponding file. The date area contains the current date and time in several forms as shown below. Finally, a working storage area of 4096 characters called "scratchpad" is provided in all programs. Code Area in Memory L Listing Area 132 characters R Card Reader Area 80 characters P Card Punch Area 80 characters 1-6 Numbered File Areas (up to 6) Length equal to record length S Scratchpad Area 4096 characters D Date Area 42 characters V Variable-length records length area. Figure 2. Work Areas in a BESTOP Program - References to data contained in the work areas include the area code, that is shown to the left of each area in figure 2, and the beginning and ending positions of the field within the area. Thus, a reference to a data field in positions 25 through 30 of the card reader area would be "R.25.30". The area codes are also used in WRITE instructions to indicate that the entire contents of an area are to be written out onto the corresponding output file. To illustrate, a program to reproduce a deck of cards must move each card image from the reader area to the punch area and then have the contents of the latter area punched into a card. The entire program consists do the following two instructions: ________________________________________________________________________ -4- 1 BESTOP ________________________________________________________________________ M R.1.80 P.1.80 W P The input cards are automatically placed in the reader area by the record reading routine. The output area is cleared to blanks after the record has been written. Constants are enclosed in apostrophes and may be used in a manner similar to data field references in many instructions. For example, if a "25" is to be punched in columns 79-80 of a deck of cards, the instruction to move that number into the punch area would be: M '25' P.79.80 The use of data contained in tables is covered in section 2. Variable length records are read and written on the basis of information contained in file header labels, JCL and the program work area "V". For variable length record files, the size of the corresponding file area (1-6) in the program is equal to the maximum size of the records in the file less the four characters required for the record descriptor work (RDW) of the variable length record. That is, a maximum logical record length of 156 for a variable length record file would require an area of 152 characters in the program as BESTOP does not store the RDW information in the work area of the file. Instead, the actual length of the records in each of the file areas is stored in the appropriate positions of area "V" as follows: Locations Actual Length of Record for V.1.4 File 1 V.5.8 File 2 V.9.12 File 3 V.13.16 File 4 V.17.20 File 5 V.21.24 File 6 For input files, the record form (RECFM), maximum record length (LRECL) and block size (BLKSIZE) are provided by the header label of the file and either fixed length (RECFM=FB or F) or variable length (RECFM=VB or V) records may be read by the program. If the record is variable length, the actual length of the record, less the RDW, is stored by the program as a decimal integer in the appropriate field within area V. Positions in the input area that are not filled by the input record are set to blanks. For output files, the record form (FB,F,VB or V), maximum record length, and block size must be provided in a data control block (DCB) 0 ________________________________________________________________________ -5- 1 BESTOP ________________________________________________________________________ entry for the file in the JCL. For variable length records (VB,V), the LRECL of the DCB entry must include 4 positions for the RDW. The actual length of a variable length record, excluding the RDW, must be stored by the programmer in decimal integer form in the appropriate field within area V before the record is written. The contents of that field are not affected by the record writing operation. A record of the maximum length is written if the record length field in area V contains a zero, blanks, or non-numeric characters. Locations Date or Time 1-18 Long form date, right justified (e.g., November 25, 1971) 19-26 Short form date, right justified (e.g., 11/25/71) 27-32 Standard form, YYMMDD (e.g., 71329) 33-37 Julian form, YYDDD (e.g.), 71329) 38-42 Starting time of run, HH:MM - - - - - - - - ________________________________________________________________________ -6- 1 BESTOP ________________________________________________________________________ III.__INSTRUCTION_SPECIFICATIONS + ____ ___________ ______________ 0 A.__Instructions + __ ____________ BESTOP instructions fall into categories as follows: 1. Conditional Instructions I - IF O - OTHERWISE U - UNCONDITIONAL 2. Processing Instructions M - MOVE E - EDIT C - CLEAR + - ADD - - SUBTRACT X - MULTIPLY / - DIVIDE W - WRITE G - GET H - HALT B - BRANCH L - LOOKUP F - FIND M - MOVE (TO DISPLACED FIELD) M - MOVE (FROM DISPLACED FIELD) D - DO AGAIN 3. Subroutine Definition Instructions S - SUBROUTINE R - RETURN 4. Table Definition Instructions T - TABLE constant - ENTRY 5. Matched File Instruction K - KEYS - 0 ________________________________________________________________________ -7- 1 BESTOP ________________________________________________________________________ BESTOP instructions generally consist of an operation code followed by parameters which may include field specifications, constants, and modifiers. The single exception to this rule is the table entry which is coded as a single constant without an operation code. Field specifications are of the form "f.s.e" where "f" is the file code, "s" is the starting location, and "e" is the ending location. For example, the specification R.23.28 refers to positions 23 through 28 of the reader area. The ending location, with its separating period, may be omitted for single character fields as in L.67, a reference to position 67 of the listing area. Constants are enclosed in apostrophes. If it is necessary to include an apostrophe within a constant, it should be coded as two contiguous apostrophes. The compiler will omit the second apostrophe from the resulting constant. Modifiers are single character parameters that are used to invoke specific forms of some instructions. Only one instruction may be coded on a single card or line. Instructions may be numbered by coding a decimal number prior to the operation code. Comments may follow an instruction or instruction number by coding an asterisk (*) to indicate that the remaining portion of the line or card is a comment. The instruction numbers, operation code, parameters, and instruction comment must all be separated by at least one blank. Instructions, including numbers, comments and spacing, may not exceed 80 characters. Several notation conventions have been followed in the instruction specifications. Operation codes and modifiers are denoted with their actual upper case letters, numbers, or special characters. The lower case words 'field' and 'const' denote a field or constant parameter respectively. A blank parameter (which may be omitted) is denoted with the special symbol "( )". Stacked brackets indicate that one of the parameters in the stack should be selected. B.__Conditional_Instructions + __ ___________ ____________ The conditional instructions (IF, OTHERWISE, and UNCONDITIONAL) are used to start routines and to establish the conditions that must be met before a routine will be executed. A routine may start with one or more "IF" instructions which establish a set of conditions, with an "OTHERWISE" instruction which identifies a routine that is to be executed if the previous IF instruction routine was not executed, or with the UNCONDITIONAL instruction which is needed to start a routine that will be executed unconditionally following an IF or OTHERWISE routine. IF, OTHERWISE and UNCONDITIONAL instructions may never be used together within a single routine. The OTHERWISE instruction may only be used to start a routine that immediately follows an IF routine. The 0 ________________________________________________________________________ -8- 1 BESTOP ________________________________________________________________________ UNCONDITIONAL instruction is only used immediately after IF or OTHERWISE routines and is not used at the start of a program or subroutine, or immediately following a subroutine or table. The various forms of the IF instruction end with the linking modifiers A,O, or blank for "and", "or" and "no link" respectively. A linking modifier specifies the relationship between the current IF instruction and the IF instruction that follows. It must be left blank if the next instruction is not an IF instruction. When both "and" and "or" links are used as modifiers in a set of IF instructions, the "and" links take precedence over the "or" links. Thus, in a set of condition instructions with tests X, Y, and Z that are linked as follows: X and Y or Z, the correct interpretation is as though parenthesis were used to group the tests as: (X and Y) or Z and not as: X and (Y or Z) 1.__IF_(Character_Field_Comparison) +__ __ __________ _____ ___________ ------------------------------------------------------------------------ (E) (A) I field (G) (field) (O) (L) (const) ( ) (U) ------------------------------------------------------------------------ The contents of the first field are compared with the second for the relationship specified by the first modifier as follows: E - first equals second G - first is greater than second L - first is less than second U - first is unequal to second The two fields must be the same size. The comparison is made on character for character basis from left to right until two unequal characters are compared on the fields are exhausted. 0 ________________________________________________________________________ -9- 1 BESTOP ________________________________________________________________________ 2.__IF_(Numeric_Field_Comparison) +__ __ ________ _____ ___________ ------------------------------------------------------------------------ (E) (A) I N field (G) (field) (O) (L) (const) ( ) (U) ------------------------------------------------------------------------ The numeric values of the contents of the two fields are compared for the relationship specified by the second modifier as follows: E - first equals second G - first is greater than second L - first is less than second U - first is unequal to second The fields need not be the same size since it is the numeric value and not the character values of the two fields that are compared. In the numeric comparison, values are ranked from plus infinity (high) to minus infinity (low). Blanks are equivalent to zeros. The digits 0 through 9, blanks and minus signs are the only characters that may appear in a field or constant used in a numeric comparison. Example Test the contents of file 1 positions 12-19 for a value greater than zero. I N 1.12.19 G '0' 3.__IF_(Multiple_Comparison) +__ __ _________ ___________ ------------------------------------------------------------------------ (E) (A) I M field (U) const (O) ( ) ------------------------------------------------------------------------ The field is compared against a list of values specified in the constant on a character by character basis. Each value in the constant must have the same length as the field. Individual comparison values within the constant must be separated by commas or dashes and not blanks. However, blanks may be included in the comparison values. Commas in the constant separate discrete values while a dash indicates a range of values whose limits are specified by the two values joined by the dash. ________________________________________________________________________ -10- 1 BESTOP ________________________________________________________________________ When the second modifier is an "E", the test is satisfied if the contents of the field are identical to any of the values in the list or if they fall within a range specified in the list. When the second modifier is a "U", the test is satisfied only if the contents of the field are not identical to any of the values in the list and do not fall within a range specified in the list. Examples Test the code in reader positions 8-9 for the values 05, 09, or 16 or a value in the range from 25 to 29. I M R.8.9 E '05,09,16,25-29' Test the code in file 1 position 15 for a value that is not equal to a blank, 2, or 9 and that does not fall in the range from 4 to 7. I M 1.15 U ' ,2,4-7,9' 4.__IF_(character_comparison) +__ __ __________ ___________ ------------------------------------------------------------------------ I C field (E) const (U) ------------------------------------------------------------------------ Each individual character in the field is tested against the set of characters contained in the constant for the equal (E) or unequal (U) relationship specified in the instruction. The equal test is met if all of the characters in the field are found in the constant. The unequal test is met if any of the characters in the field are missing from the constant. Example Set the contents of 1.6.9 to blank if it contains non-numeric characters. I C 1.6.9 U '0123456789' C 1.6.9 ' ' - - ________________________________________________________________________ -11- 1 BESTOP ________________________________________________________________________ 5.__IF_(Control_Break) +__ __ ________ ______ ------------------------------------------------------------------------ (A) I field (0) ( ) ------------------------------------------------------------------------ The contents of the field are compared with the contents of the same field at the time of the last testing of the conditions for the current routine. The test is satisfied if there has been a change in the contents. It is never satisfied the first time that it is executed as there is no basis for a comparison. A control break is always satisfied on the last pass to permit the processing of group totals and similar end of group results. 6.__IF_(Printer_Line_Test) +__ __ ________ ____ _____ ------------------------------------------------------------------------ (E) (A) I C (G) const (0) (L) ( ) (U) ------------------------------------------------------------------------ The contents of the printer line counter are compared against a two digit zero filled constant for the relationship specified by the second modifier as follows: E - counter equals constant G - counter is greater than constant L - counter is less than constant U - counter is unequal to constant 7.__IF_(Condition_Test) +__ __ __________ _____ ------------------------------------------------------------------------ (M) (A) I (A) (0) (B) ( ) (S) (F) ------------------------------------------------------------------------ This instruction tests for condition specified by the first modifier as follows: ________________________________________________________________________ -12- 1 BESTOP ________________________________________________________________________ M - Matching records were read from the two input files under matched file control. A - There is an unmatched record in the A file that was read under matched file control. B - There is an unmatched record in the B file that was read under matched file control. S - Start of run, the first record(s) is being processed. F - Finish of run, the last record(s) has been processed and the program is in the last pass. 8.__OTHERWISE +__ _________ ------------------------------------------------------------------------ O ------------------------------------------------------------------------ The OTHERWISE instructions is used to start a routine that should be executed if the conditions set forth for the immediately previous routine were not met. It may only be used after a routine that begins with an IF instruction. 9.__UNCONDITIONAL +__ _____________ ------------------------------------------------------------------------ U ------------------------------------------------------------------------ The UNCONDITIONAL instruction is used to end the routine associated with the previous set of condition instructions and to start a new routine that will be executed unconditionally. - - - - ________________________________________________________________________ -13- 1 BESTOP ________________________________________________________________________ C.__Data_Movement_Instructions + __ ____ ________ ____________ The basic data movement instructions are the MOVE, EDIT, and CLEAR. The MOVE instruction moves data from one field to another in memory or moves a constant into a field. The EDIT instruction moves data from one field to another and inserts any necessary punctuation. The CLEAR instruction fills a field with any desired character and can be use for such operations as clearing counters or drawing lines of dashes across a page. 1.__MOVE +__ ____ ------------------------------------------------------------------------ M (field) field (const) ------------------------------------------------------------------------ The contents of the first field (or constant) are copied into the positions specified by the second field. The sending and receiving fields must have the same length. 2.__EDIT +__ ____ ------------------------------------------------------------------------ E field field const ------------------------------------------------------------------------ The contents of the first field are edited with the symbols contained in the constant and placed in the second field. Zeros or blanks in the constant are replaced by characters from the first field. All other characters in the constant will appear in the same relative positions within the second field. A zero in the constant indicates that leading zeros should appear in any blank positions to the right of and including the zero position and that leading commas in the constant to the left of the zero should be suppressed. Blanks are used in the remaining positions of the constant corresponding to positions to be occupied by data from the first field. The length of the constant must be equal to the length of the second field and should contain enough replaceable blanks and zeros to accommodate the characters of the first field. This operation may only be performed on numeric data. Examples Read area positions 31-39 contain a dollar amount expressed to the nearest hundredth of a dollar. Edit the field to insert commas and decimal point 0 ________________________________________________________________________ -14- 1 BESTOP ________________________________________________________________________ where appropriate and place the edited result in listing positions 42-53. E R.31.39 L.42.53 ', , .0 ' Zero fill the contents of file 1 positions 8-12 and place the result in file 2 positions 1-5 E 1.8.12 2.1.5 '0 ' 3.__CLEAR +__ _____ ------------------------------------------------------------------------ C field const ------------------------------------------------------------------------ All of the positions in the specified field are filled with the single character specified by the constant. Example Draw a line of dashes across the next line of the listing. C L.1.132 '-' D.__Arithmetic_Instrictions + __ __________ ____________ The arithmetic instructions are the ADD, SUBTRACT, MULTIPLY, and DIVIDE. Arithmetic operations may be performed on positive or negative data. Minus signs, if any, must be carried to the left of the first significant digit in a field. Positive or zero data should be left unsigned; the positive or zero results of any computations are always unsigned. All arithmetic operations are algebraic, i.e., the signs of any data items used in a computation are taken into account. 1.__ADD +__ ___ ------------------------------------------------------------------------ + (field) field (const) ------------------------------------------------------------------------ The contents of the first field or constant are added to the second field. The result replaces the second field. 0 ________________________________________________________________________ -15- 1 BESTOP ________________________________________________________________________ The width of the first field or constant must not be larger than the width of the second field. 2.__SUBTRACT +__ ________ ------------------------------------------------------------------------ - (field) field (const) ------------------------------------------------------------------------ The contents of the first field or constant are subtracted from the second field. The result replaces the second field. The width of the first field or constant must not be larger than that of the second field. 3.__MULTIPLY +__ ________ ------------------------------------------------------------------------ X field (field) (0-9) field (const) ------------------------------------------------------------------------ The first field is multiplied by the second or by the constant and the rounded result is placed in the third field. The single digit modifier indicates the number of digits that will be rounded from the result. Example Multiply the contents of read area positions 11-17 by read area positions 18-23. Round the result three places and place it in file 1 positions 21-30. X R.11.17 R.18.23 3 1.21.30 4.__DIVIDE +__ ______ ------------------------------------------------------------------------ / field (field) (0-9) field (const) ------------------------------------------------------------------------ The first field is divided by the second or by the constant and the result is placed in the third field. Prior to the division operation, the first field is extended by the number of zeros specified in the modifier to obtain greater precision. ________________________________________________________________________ -16- 1 BESTOP ________________________________________________________________________ The value of the precision modifier can be calculated from the following formula for fields with implied decimal locations: Modifier = B - A + C where: B = the implicit number of decimal places in the divisor, A = the implicit number of decimal places in the dividend, and, C = the implicit number of decimal places required in the result. Example The total income in dollars for a group of people is contained in file 1 positions 35-44 and the number of people in the group is contained in file 1 positions 51-56. Compute the per capita income to the nearest hundredth of a dollar and place the result in file 2 positions 11-16. / 1.35.33 1.51.56 2 2.11.16 E.__Output_And_Control_Instructions + __ ______ ___ _______ ____________ The output and control instructions are the WRITE, GET, and HALT. The WRITE instruction is used to write records from the various output areas of the program. It is also used to control the vertical spacing of the printer. There is no record reading instruction as that operation is performed by the record reading routine. However, the GET instruction will cause an immediate return to the record reading routine to get and process the next record without executing any remaining instructions in the program on the current record. The HALT instruction may be used to stop the program before the end of the input file(s). 1.__WRITE_(Numbered_Files_and_Punch_File) +__ _____ _________ _____ ___ _____ _____ ------------------------------------------------------------------------ W (1-6) (P) ------------------------------------------------------------------------ A record is written from the specified output area and the area is cleared to blanks. - 0 ________________________________________________________________________ -17- 1 BESTOP ________________________________________________________________________ 2.__WRITE_(Listing_with_Spaces) +__ _____ ________ ____ _______ ------------------------------------------------------------------------ W L (1-9) (H) ------------------------------------------------------------------------ A line is printed with the contents of the listing area and the area is cleared to blanks. The printer is spaced from 1 to 9 lines or to the head of form (H). 3.__WRITE_(Listing_with_Skip_to_Numbered_Line) +__ _____ ________ ____ ____ __ ________ _____ ------------------------------------------------------------------------ W L S const ------------------------------------------------------------------------ A line is printed with the contents of the listing area and the area is cleared to blanks. The printer skips to the line specified in the two digit zero-filled constant after printing the line. Example Write a line and skip to line 52. W L S '52' 4.__Write_(Space_Printer_without_Printing) +__ _____ ______ _______ _______ _________ ------------------------------------------------------------------------ W S (1-9) (H) ------------------------------------------------------------------------ The printer is spaced from 1 to 9 lines or to the head of form (H) without printing a line. The contents of the listing area remain unchanged. 5.__WRITE_(Skip_to_Numbered_Line_without_Printing) +__ _____ _____ __ ________ ____ _______ _________ ------------------------------------------------------------------------ W S const ------------------------------------------------------------------------ - ________________________________________________________________________ -18- 1 BESTOP ________________________________________________________________________ The printer is skipped to the line specified in the two digit zero-filled constant without printing a line. The contents of the listing area remain unchanged. 6.__GET +__ ___ ------------------------------------------------------------------------ G ------------------------------------------------------------------------ The processing of the current record(s) is terminated and the program makes an immediate return to the record reading routine to get the next record(s). Processing resumes with the first instruction in the program. 7.__HALT +__ ____ ------------------------------------------------------------------------ H (R) (J) ------------------------------------------------------------------------ The current run or step (R) or the entire job (J) is terminated as specified by the modifier. In terminating the run, the program executes the last pass and closes all input and output files before returning to the operating system. F.__Soubroutine_Linkage_Instruction + __ ___________ _______ ___________ Subroutines may be included in BESTOP programs by using the SUBROUTINE instruction to identify the subroutine and following it with the routine(s) that are to be included in the subroutine. The subroutine is terminated by a RETURN instruction. A subroutine is executed with a BRANCH instruction. After the subroutine has been executed, control returns to the instruction following the BRANCH. Subroutines may not be defined within other subroutines although they may contain branches to other subroutines. Care must be taken to avoid constructing a string of branches which includes a branch back to a subroutine earlier in the string. Such a sequence will destroy the return linkage back to the calling routine. A subroutine may only be entered with a branch instruction. It is skipped when encountered in the normal execution of the routines in a program. Any number of branches may be made to the same subroutine. - - ________________________________________________________________________ -19- 1 BESTOP ________________________________________________________________________ 1.__SUBROUTINE +__ __________ ------------------------------------------------------------------------ S (1-9) (A-Z) ------------------------------------------------------------------------ A subroutine is started which is identified by the single digit or letter specified in the modifier. All instructions following the SUBROUTINE instruction up to the final RETURN instruction are included in the subroutine. 2.__RETURN +__ ______ ------------------------------------------------------------------------ R (C) ( ) ------------------------------------------------------------------------ A return is made to the instruction following the branch to the subroutine. If the modifier is omitted, the subroutine is terminated. The modifier "C" indicates that the instructions following the RETURN are to be included in the subroutine until a terminating RETURN is encountered, that is a subroutine may have multiple returns. 3.__BRANCH +__ ______ ------------------------------------------------------------------------ B (1-9) (A-Z) ------------------------------------------------------------------------ A branch is made to the subroutine identified by the modifier. Control returns to the instruction following the branch after the subroutine has been executed. G.__Table_Lookup_Instructions + __ _____ ______ ____________ A table lookup may be used to obtain a title, code, or other item that corresponds to a value shown in a table. It is useful in coding and recoding data and in translating codes into titles. A table is made up of a number of constant width entries. Each entry has two parts, an argument, the test value, and the result, the code or title to which the argument corresponds. A table is defined with a TABLE instruction followed by the entires of the table. It is searched with a LOOKUP instruction. In the lookup operation, a program argument in a specified field is tested against the arguments of the table and a result corresponding to 0 ________________________________________________________________________ -20- 1 BESTOP ________________________________________________________________________ the table argument that meets the specified lookup test is stored in a result field. The program argument and result fields are specified in the TABLE instruction. The lookup test is specified in the LOOKUP instruction. The result field is cleared to blanks if there is no table argument that meets the lookup test. 1.__TABLE_DEFINITION +__ _____ __________ ------------------------------------------------------------------------ T (1-9) field field (A-Z) ------------------------------------------------------------------------ A table is created and identified by the single digit or letter specified in the modifier. The first field specifies the location of the lookup argument; the second specifies the location into which the result will be placed. The entries of the table follow the TABLE instruction. The length of each entry must be equal to the sum of the lengths of the argument and result fields. 2.__TABLE_ENTRY +__ _____ _____ ------------------------------------------------------------------------ const ------------------------------------------------------------------------ A table entry is generated from the specified constant. The leftmost portion of the constant is assumed to be the table argument and the rightmost is assumed to be the table result. The lengths of the table argument and result portions of the constant are assumed to be equal to the lengths of the argument and result fields specified in the TABLE instruction 3.__LOOKUP +__ ______ ------------------------------------------------------------------------ L (1-9) (E) (A-Z) (L) (H) ------------------------------------------------------------------------ A search is made of the table specified in the first modifier for the entry which meets the test specified by the second modifier as follows: E - Lookup equal, the program will select a table entry only if the argument in the entry is 0 ________________________________________________________________________ -21- 1 BESTOP ________________________________________________________________________ equal to the contents of the program argument specified in the TABLE instruction. If the table argument is equal to the program argument , the table result is stored in the result field specified in the TABLE instruction. The result area is cleared to blanks if there is no equal entry. L - Lookup low or equal, the program searches for the entry whose argument is the highest of those with arguments lower than or equal to the program argument and the corresponding result is moved to the result field. The result field is cleared to blanks if there are no entries in which the argument is lower than or equal to the program argument. H - Lookup high or equal, the program searches for the entry whose argument is the lowest of those entries with arguments higher than or equal to the program argument and the corresponding result is moved to the result field. The result field is cleared to blanks if there are no entries in which the argument is higher than or equal to the program argument. H.__Matched_File_Control + __ _______ ____ _______ A program will read two input files when the necessary information is provided to further specialize the record reading routine. Otherwise, a program is limited to one input file. Both files must be sorted on an identical set of sequence keys although these keys may occupy different positions in the records of the two files. For identification purposes, one file is designated the A file and the other is designated the B file. The record reading routine compares the sequence keys in the current records from each file and sets one of the following three indicators: M - The records in the two files are matching records. A - There is a record in the A file which is not matched in the B file, i.e., the value of the keys in the current A file record is less than that for the current B file record. 0 ________________________________________________________________________ -22- 1 BESTOP ________________________________________________________________________ B - There is a record in the B file which is not matched in the A file, i.e., the value of the keys in the current B file record is less than that for the current A file record. These indicators may be tested with the condition test form of the "IF" instruction. Subsequent record reading operations are controlled by the previous setting of the above indicators and the "run type." The run type codes are the following: 1 - There should be one record in file A for each record in file B. If either file contains two records with the same values in the sequence keys, the program will treat the second record as an unmatched record. 2 - There may be more than one record in file B for each file A record. However, there should be no more than one file A record for each file B record. Thus, duplicate file B records will be treated as matches for a single file A record while duplicate file A records will be treated as unmatched records. A record from the A file is always read by the record reading routine if the A indicator was set after the last reading operation. A record from the B file is always read if the B indicator was set. If the M indicator was set and the run type is "1", both an A and a B file record are read before they are compared and an indicator is set on the basis of that comparison. If the M indicator was set and the run type is "2", a B file record is read first and compared with existing A file record. The M indicator is then set if they match. If they do not match, an A file record is read and the comparison is repeated before an indicator is set. At the end of the record reading operation the current A file record will appear in the memory area corresponding to the A file code and the current B file record will appear in the memory area corresponding to the B file code. If either file has been exhausted, the corresponding area will be filled with padding (the hexadecimal character FF). Up to five sequence keys may be used in the record comparison. The locations of these keys in major to minor order for the records in each of the two files is specified in a KEYS instruction. The run type and the A file and B file specifications are job control language parameters. ________________________________________________________________________ -23- 1 BESTOP ________________________________________________________________________ 1.__MATCH_KEYS +__ _____ ____ ------------------------------------------------------------------------ K field field (field field). . .(field field) ------------------------------------------------------------------------ The KEYS instruction specifies up to five pairs of sequence keys in the records of the A and B files that establish the order of the two files. The first field in each pair specifies the location of a sequence key in the A file records while the second field specifies the location in the B file records. The order of the pairs within the instruction must be a major to minor. The widths of the two fields within a pair must be equal although different pairs may have different widths and the actual locations of the keys within the records of the two files need not be the same. I.__Advanced_Techniques + __ ________ __________ Several instructions are available that emulate array processing. The first three instructions use a displacement field in their operations. It provides a capability similar to indexing or subscripting in other languages. The displacement is a 1 to 4 digit number that specifies a character location within a field in terms of the number of characters between the specified character and the first character of the field. For example, the displacement of the 25th character of a field is 24 as it is displaced 24 character positions from the 1st character. The displacement itself is stored in a field 1 to 4 characters long and is always preceded by the modifier "D". For example, a displacement stored in scratchpad positions 22 to 25 would be expressed in the form: D S.22.25 The "DO AGAIN" instriction provides the capability similar to the DO WHILE of PL/1. 1.__FIND +__ ____ ------------------------------------------------------------------------ F (field) field D field (const) ------------------------------------------------------------------------ The second field is searched for a character string that is identical to the contents of the first (or constant). The displacement of the first character of the found string within the second field is placed in the third field. The third field is cleared to blanks if the string is not found. The search beings at the character within the field that is specified by the initial value of the displacement. 0 ________________________________________________________________________ -24- 1 BESTOP ________________________________________________________________________ Example Find the displacement of the character string "#7609" within the field 1.20.80 and record the displacement in S.1.4. F '#7609' 1.20.80 D S.1.4 Notes 1. The search beings at the first position of the second field if the initial value of the displacement is blank or zero. 2. The search ends when the number of characters remaining in the second field is less than the number of characters in the first field. 3. The resulting displacement is always stored without leading zeros except that a zero displacement is stored as a single zero. A resulting displacement that is blank indicates that he string was not found. 4. The leftmost digits of the resulting displacement are truncated if there are more characters in the displacement value than in the displacement field. 5. The displacement field may not be more than 4 characters wide. 2.__MOVE_(to_displaced_field) +__ ____ ___ _________ ______ ------------------------------------------------------------------------ M (field) field D field (const) ------------------------------------------------------------------------ The contents of the first field or constant are moved to the locations in the second field that are specified by the displacement in the third field. The entire contents of the first field are moved if the number of positions between the displaced location in the second field and the end of the second field is greater than or equal to the length of the first field. Unfilled positions in he second field retain their original values. The right most positions of the field are not 0 ________________________________________________________________________ -25- 1 BESTOP ________________________________________________________________________ moved if their is insufficient space in the displaced locations in the second field. The operation is not executed if the value of the displacement is greater than or equal to the width of the second field. Example Given the specified contents of the following fields: 2.40.45 "A3 " S.1.2 " 2" The instruction M ';' 1.40.45 D S.1.2 changes the contents of 2.40.45 to "A3; " Notes 1. The displacement field may not be more than 4 characters wide. 2. The MOVE operation is not executed if the displacement field contains non-numeric characters. 3.__MOVE_(from_displaced_field) +__ ____ _____ _________ ______ ------------------------------------------------------------------------ M field D field field ------------------------------------------------------------------------ The third field is filled with characters from the first field starting with the character in the first field that is specified by the displacement in the second field. The third field is filled completely unless there is an insufficient number of characters in the displaced portion of the first field. Unfilled positions in the third field retain their original values. Example Given the specified contents of the following fields: ________________________________________________________________________ -26- 1 BESTOP ________________________________________________________________________ 1.8.14 "ABCDEFG" S.6.8 " 2" 2.4.7 "HIJK" The instruction M 1.8.14 D S.6.8 2.4.7 changes the contents of 2.4.7 to: "CDEF" Notes 1. The displacement field may not be more than 4 characters wide. 2. The MOVE operation is not executed if there are non-numeric characters in the displacement field. 4.__DO_AGAIN +__ __ _____ ------------------------------------------------------------------------ D ------------------------------------------------------------------------ This instruction causes the IF instructions at the beginning of the routine containing the DO AGAIN instruction to be retested. The instruction should always be the last instruction in a routine as is it will prevent any remaining instructions in the routine from being executed. The IF condition at the start of the routine must be designed to terminate the looping effect of the DO AGAIN instruction after the desired number of iterations. To avoid indefinite looping, the program will terminate abnormally (condition code 16) if any combination of DO AGAIN instructions is executed 1000 times without reading a record. Example Branch to subroutine A seven times. C S.8 '0' I S.8 L '7' 0 ________________________________________________________________________ -27- 1 BESTOP ________________________________________________________________________ B A +'1'S.8 D Notes The DO AGAIN may also be used in a routine started by an UNCONDITIONAL instruction when that routine calls a subroutine which executes a GET instruction as a means of terminating the looping effect. - - - - - - - - - - - - ________________________________________________________________________ -28- 1 BESTOP ________________________________________________________________________ IV.__PROGRAMMING_TECHNIQUES + ___ ___________ __________ 0 A.__Routines + __ ________ Within a routine, instructions are arranged in the order in which they are to be executed. Most routines begin with a set of conditional instructions that establish conditions which must be met before the processing instructions of the routine will be executed. If the conditions are not met, the routine is skipped until the next pass through the object program. When present, conditional instructions (IF, OTHERWISE, UNCONDITIONAL) must always come before the processing instructions in a routine. Example: Routines File 1 contains records that are 25 characters long with the following code position 14: 1 - MALE 2 - FEMALE 3 - DATA ERROR Recode female records with the code "4" and write the recoded file as File 2. Print any records with invalid codes. Only records with valid codes should be written on file 2. The resulting program contains four routines and is shown below. The instructions have been numbered for identification and sequence purposes. Instruction numbers may precede the operation code of any instruction. They are not checked by the BESTOP Compiler and are ignored during the compilation process. For purposed of discussion, the routines in each example are identified by the number of the first instruction in the routine. 1 M 1.1.25 2.1.25 2 I 1.14 E '2' 4 M '4' 2.14 5 I 2.14 U '1' A 6 I 2.14 U '4' 7 M 2.1.25 L.1.25 8 W L 1 9 O 10 W 2 ________________________________________________________________________ -29- 1 BESTOP ________________________________________________________________________ Routine 1 Unconditionally moves a copy of each record to the File 2 areas. The first routine in a program is always executed unconditionally when no "IF" instructions are included in the routine. 2 Tests position 14 of each input record for code "2" and assigns the new code "4" to records that meet that test. 5 Prints those records that have a code that is unequal to both "1" and "4." The lines are single spaced. 9 Writes all of the records that have valid codes, i.e., all those that were not processed by routine 5. Any of the following instructions will start a routine: 1. A conditional instructions following a processing instruction. 2. The first instruction in a program or subroutine. 3. The first instruction following a subroutine or table. A routine ends with the last instruction prior to: 1. The next routine 2. A table or subroutine. 3. The end of the program. B.__Subroutines + __ ___________ Subroutines start with a SUBROUTINE instruction and end with a RETURN instruction. All of the routines between these two instructions are included in the subroutine. A subroutine may not be started within another subroutine, i.e., a SUBROUTINE instruction may not appear between the SUBROUTINE instruction of another subroutine and its terminating RETURN instruction. - ________________________________________________________________________ -30- 1 BESTOP ________________________________________________________________________ Subroutines may be placed anywhere in a program since they are not executed when they are encountered; they are executed only by a BRANCH to the subroutine. Control returns to the instruction following the BRANCH after the subroutine has been executed. Example: Subroutines File 2 contains records that are 60 characters long with the following code fields: Location Contents 1-5 Individual identification number 16 Race 1 - white 2 - negro 3 - other non-white 34 Sex 1 - male 2 - female Screen the file for valid sex and race codes and print the following line for each invalid code: Location Contents 1-5 Individual identification number 7 Race 9 Sex 11-27 Error message "INVALID RACE CODE" "INVALID SEX CODE" The resulting program contains three routines, one of which is enclosed in a subroutine. 1 I 2.16 L '1' 0 2 I 2.16 G '3' 3 M 'INVALID RACE CODE' L.11.27 4 B 1 5 I 2.34 U '1' A 6 I 2.34 U '2' 7 M 'INVALID SEX CODE' L. 11.26 8 B 1 9 S 1 10 M 2.1.5 L.1.5 11 M 2.16 L.7 12 M 2.34 L.9 0 ________________________________________________________________________ -31- 1 BESTOP ________________________________________________________________________ 13 W L 1 14 R Routine 1 Moves the message "INVALID RACE CODE" to the listing area if the race code is under 1 or greater than 3. Branches to Subroutine 1 to complete the printing of the error message. 5 Moves the message "INVALID SEX CODE" to the listing area if the sex code is unequal to both 1 and 2. Branches to Subroutine 1 to complete the printing of the error message. 9 The start of a subroutine which ends with the RETURN instruction number 14. The subroutine includes only one routine but could contain any number that might be required. 10 A routine which completes and prints a standard error message. While the routine is executed unconditionally, it is only executed when a branch is made to subroutine 1. C.__Tables + __ ______ A table consists of a TABLE instruction followed by one or more ENTRIES. The TABLE INSTRUCTION identifies the table name and specifies the field containing the argument to be used in lookup operations and the field that is to contain the result of the lookup. Each entry in the table is a single constant which includes an argument and a result in that order. A table ends with the last entry prior to an instruction that is not an entry or with the end of the program, whichever comes first. Tables are used only by lookup instructions and may be placed anywhere in a program. Example: Table Lookup File 1 contains 35 character records on individuals with the age of the individual recorded with leading zeros in positions 12-13. The age of the individual must be coded in the manner shown below and the age code should be added to the end of each record to produce a new record which should be written on File 2. 0 ________________________________________________________________________ -32- 1 BESTOP ________________________________________________________________________ CODE AGE 1 UNDER 14 2 14-19 3 20-24 4 25-34 5 35-44 6 45-54 7 55-64 8 65 AND OVER The program consists of a single routine and table. 1 M 1.1.35 2.1.35 2 L 1 H 3 W 2 4 T 1 1.12.13 2.36 5 '131' 6 '192' 7 '243' 8 '344' 9 '445' 10 '546' 11 '647' 12 '998' Routine 1 Moves the input record to the output area, performs a table lookup to get the required age code and writes the coded record onto File 2. The "lookup high or equal" form of the lookup instruction has been used to stratify the data into age classes corresponding to the resulting codes. 4 A table whose entries extend through instruction number 12. When a lookup operation is executed, the program argument will be taken from field 1.12.13 and the result will be placed in field 2.36. - ________________________________________________________________________ -33- 1 BESTOP ________________________________________________________________________ D.__Matched_Input_Files + __ _______ _____ _____ A program may read and match two input files as long as both are in the same sequence on a similar set of key fields. One file is arbitrarily designated as the "A" file, and the other is then the "B" file. A special form of the IF instruction permits program tests for matching records or for unmatched records in either file. A run type code must also be specified to indicate whether more than on B file records may match a single A file record. The sequence keys for the two files are specified in the KEYS instruction. The designation of the A file, B file and run type is handled through the execute parameter in the job control language. Example: Matched File Operations Match a set of correction cards against the 120 character master file records in file 1 using the state and industry codes in the two files as the basis for the match. If there is a match, replace the income data in file 1 with the income data from the transaction cards. If there are unmatched correction cards, print the card and construct a new record containing only the state, industry, and income fields. The remaining records from file 1 should be copied onto the updated file. Both files are in order by state and industry. File 1 format (required fields only) Location Contents 2-3 State code 26-29 Industry code 41-48 Income Card format Location Contents 1-2 State code 3-6 Industry code 7-14 Income ________________________________________________________________________ -34- 1 BESTOP ________________________________________________________________________ The run type (1) and the A (File 1) and B (Reader) files are specified in the job control language. The first instruction in the program specifies the location of the keys to be used in the match. The remaining instructions are grouped into four routines to handle each of the possible match or mismatch situations and to write the output file. 1 K 1.2.3 R.1.2 1.26.29 R.3.6 2 I M 3 M 1.1.120 2.1.120 4 M R.7.14 2.41.48 5 I B 6 M R.1.14 L.1.14 7 W L 1 8 M R.1.2 2.2.3 9 M R.3.6 2.26.29 10 M R.7.14 2.41.48 11 I A 12 M 1.1.120 2.1.120 13 U 14 W 2 Routine 2 Replaces the income field in the income record with the income field from the matching correction card. 5 Prints the unmatched correction card and constructs a new output record containing the state, industry and income fields. 11 Moves records that are not to be corrected to the output file. 13 Writes an output record, regardless of its source. - - - - 0 ________________________________________________________________________ -35- 1 BESTOP ________________________________________________________________________ E.__Page_Format_Control + __ ____ ______ _______ A two character zero filled line counter provides the essential element of control in the printing of page headings, the skipping of the printer to a specific line or to the next page, and the execution of similar functions that affect the page layout of a report. The line counter records the position of the next line to be printed on a page. It is set to "01" when the printer is at the top of the page and is incremented an appropriate amount with each WRITE instruction that is directed to the printer. It is reset to "01" with a skip to the top of a new page. The counter may be tested with the "printer line test" form of the IF instruction. Example: Page Format Control Print the fields specified in the line format below from each record in File 1. Print the report title "Average Income Report" at the top of each page along with a page number and date. Print appropriate headings over the columns of data. Do not print beyond the 54th line of each page. File 1 Format (required fields only) Location Contents 8 Region 14-15 Age 18 Race 22 Sex 31-36 Average Income (unedited) Location Contents 4 Region 11-12 Age 19 Race 26 Sex 33-39 Average Income (edited XXX,XXX) - ________________________________________________________________________ -36- 1 BESTOP ________________________________________________________________________ The program consists of three routines as follows: 1 I C G '54' 2 W S H 3 I C E '01' 4 M 'AVERAGE INCOME REPORT' L.1.21 5 M 'PAGE' L.32.35 6 + '1' S.1.3 * PAGE COUNTER 7 M S.1.3 L.37.39 8 W L 1 9 M D.1.18 L.1.18 * DATE 10 W L 2 11 M 'AVERAGE' L.34.40 12 W L 1 13 M 'REGION AGE RACE' L.1.20 14 M 'SEX INCOME' L.25.39 15 W L 2 16 U 17 M 1.8 L.4 * REGION 18 M 1.14.15 L.11.12 * AGE 19 M 1.18 L.19 * RACE 20 M 1.22 L.26 * SEX 21 E 1.31.36 L.33.39 ' , ' 22 W L 1 Routine 1 Tests for the end of a page (line counter value greater than 54) and skips to the top of a new page if the test is met. The line counter is then reset to '01'. 3 Prints headings at the top of the page (line counter equal to '01'); numbers and dates (from the date area) each page. It is good practice to place the heading routine immediately after the end of page routine. If the order of the two routines had been reversed, headings would not have been printed after the first page. The end of page routine would have caused the line counter to be reset to "01", but the data printing routine below would have incremented the counter to "02" with the printing of a data line before the heading routine was encountered. Care must be taken with the spacing of the constants that make up the titles in the heading. It is good practice to layout the necessary titles on a printer spacing work sheet prior to coding a heading routine. ________________________________________________________________________ -37- 1 BESTOP ________________________________________________________________________ 16 Unconditionally print the required fields from each record. The average earnings field is edited to insert a comma after the thousands digit and to suppress leading zeros. F.__Summarizing_Data + __ ___________ ____ Data in separate records may be summarized to provide group totals as long as the input file is sorted on the code field(s) that define the groups. A file may be sorted with a standard utility routine that is provided with the operating system. The "control break" form of the IF instruction is used to test for the change of a group in routines that process group totals. Example: Summarizing Data In a file of health insurance data, the records are identified by state, program, and type of service with one record for each combination of those characteristics. Each record also contains the amount in dollars expended in the specified State on the program and type of service in a calendar year. National totals are required for all expenditures, for each program, and for each type of service within a program. The file must first be sorted by program by type of service so that all of the records for a single program will be grouped together in ascending sequence by program code and within those groups in ascending sequence by type of service. In this sort the program code field is called the major key and the type of service code field is the minor key. The first few records in the sorted file might contain the following codes and data in the order shown. The records have been numbered for reference RECORD CONTENTS Record Type of Number Program Service Expenditures 1 01 3 284921 2 01 3 17634 3 01 3 43172 0 ________________________________________________________________________ -38- 1 BESTOP ________________________________________________________________________ 4 01 5 9519 5 01 5 38178 6 01 7 8027 7 01 7 23213 8 02 2 6521 9 02 3 18276 10 03 3 50332 11 03 3 9235 12 03 3 45378 13 03 5 87389 14 03 5 20426 15 03 7 72464 16 03 7 15400 17 04 2 57441 The data records have the following format: Position Contents 1-2 Program code 3-4 State code 5 Type of Service 6-12 Expenditure in dollars The resulting program contains six routines, three to print various levels of totals, an end of page routine, a heading routine, and routine which adds the expenditure data into counters. Counters have been set up in scratchpad fields S.1.7, S.8.14 and S.15.24 for the service, program and grand totals respectively. Routines to print totals appear first in the program so that totals for a completed group will be printed before the expenditures shown in the first record of a new group are added into the counters and so that a page will not start with a program or grand total. "Control break" IF instructions are used to detect changes in the program and type of service codes that signal the end of a group. An "end of run" IF instruction controls the printing of the grand total. Routines that depend on "control break" and "end of run" IF instructions are the only ones that can be executed during the "last pass: so that totals covering routines are arranged in 0 ________________________________________________________________________ -39- 1 BESTOP ________________________________________________________________________ minor to major order so that subtotals will be printed before higher level totals. 1 I 1.1.2 0 * PROGRAM BREAK 2 I 1.5 * ST OR PGM BRK 3 E S.1.7 L.21.29 * TYTPE TOTAL 4 W L 1 5 C S.1.7 * CLEAR COUNTER 6 M 1.5 L.14 7 I 1.1.2 * PROGRAM BRK 8 M 'TOTAL' L.12.16 9 E S.8.14 L.21.29 * PROGRAM TOTAL 10 W L 2 11 C S.8.14 * CLR PGM TOTAL 12 M 1.1.2 L.4.5 13 M 1.5 L.14 14 I F * US TOTAL 15 M 'ALL PROGRAMS' L.5.16 16 E S.15.23 L.19.29 17 W L 1 18 I C G '54' 19 W S H 20 I C E '01' 21 M 'PROGRAM SERVICE AMOUNT' L.2.29 22 W L 2 23 M 1.1.2 L.4.5 24 M 1.5 L.14 25 U 26 + 1.6.12 S.1.7 * TYPE TOTAL 27 + 1.6.12 S.8.14 * PROGRAM TOTAL 28 + 1.6.12 S.15.23 * US TOTAL Routine 1 Prints type of service totals with a change in either the program or type of service code. The test for a change in program code was included to avoid problems with situations such as that which arises between records 10 and 11 when a change in program code was not accompanied by a change in the type of service code. The type of service code for the next group is stored in the listing areas after the total for the last service group has been printed. The service total counter is cleared for the next service group total. 7 Prints program totals with a change in the program code. Both the program code and the service code are stored in the listing area after 0 ________________________________________________________________________ -40- 1 BESTOP ________________________________________________________________________ printing since the service code stored by routine #1 was wiped cut by the word "TOTAL." Note that the program code is only stored (and therefore printed) with a change in program. Such "group indicating" improves the readability of the resulting listing. 14 Prints the grand total at the end of the run. There is no need to clear the grand total counter as it will not be used again. 18 Skips to the top of the next page when the printer goes beyond line 54. 20 Prints column headings at the top of the page. The program and service codes are stored in the listing area to provide for the proper identification of the first date line following the headings. 25 Adds the expenditure amount from each record (unconditionally) into the service, program, and grand total counters. Note the comments throughout the program. They make the program more readable and aid in debugging. Also, should changes have to be made to the program, comments tend to be exceedinly helpful. - - - - - - 0 ________________________________________________________________________ -41- 1 BESTOP ________________________________________________________________________ V.__PROGRAM_DEBUGGING + __ _______ _________ 0 A BESTOP run produces a number of items which are useful in program debugging or in checking the results of the run. These include compilation diagnostics and end of run file dumps and record counts. It is also possible to execute runs which produce only program diagnostics. A.__Compilation_Diagnostics + __ ___________ ___________ Compilation diagnostic messages are produced during the compilation of the individual instructions and at the end of the compilation process. The instruction diagnostics note such things as unrecognized instruction patterns, invalid field specifications, incorrect sequences of instructions and overlapping fields. They are printed to the right of the instruction that is in error. End of compilation diagnostics note irregular conditions that might exist at the end of a compilation such as a missing KEYS statement in a matched file run. They are printed at the end of the instruction listing. Diagnostic errors must be corrected before a program can be executed. B.__Instruction_Diagnostics + __ ___________ ___________ An instruction diagnostic is printed as a series of dots to the left of the instruction with the dots representing the individual parameters of the instruction from left to right. The dot corresponding to the parameter that is in error is replaced by a letter that indicates the nature of the error. The meanings of the error letters are provided below. .F.... File Code Error (may occur in the second through the sixth instruction parameters) The file code of the specified field is not a legal file code. Check and recode the field specification. .I.... Write File Error - The file specified in a WRITE instruction has been specified as an input file in the EXEC statement. Check the program logic and correct either the WRITE or the EXEC statement. .L.... Field Length Error (may occur in the second through the sixth instruction parameters) The length of the specified field exceeds the maximum permitted for that type of instruction. See the appendix for instruction field length restrictions. .M.... Match File Code Error (may occur in the second through the eleventh parameters) The file code of the 0 ________________________________________________________________________ -42- 1 BESTOP ________________________________________________________________________ field specification does not match the corresponding A or B file code specified in the job control language. .O.... Field Overlap Error (may occur in two or three parameters within a single instruction) The specified fields overlap, i.e., they have one or more characters in common. Overlapping fields are not permitted within a single instruction. Recode the instruction to eliminate the overlap or replace it with two or more instructions which will perform the desired operation without overlapping fields within a single instruction. .P... Instruction Pattern Error - There is no instruction in the BESTOP language with the particular pattern of operation code, constant, field specifications and modifiers as that specified. Recheck the description of the desired instruction. .R... Field Range Error (may occur in the second through the sixth instruction parameters) Part or all of the specified field is beyond the limit of the records in the specified file. For input files the limit is the actual record length as specified in the data set label. For numbered output files the limit is 4096 bytes unless record lengths are provided in the DD statements for the output files. Record length limits for the reader, punch and listing files are 80, 80 and 132 respectively. The limit for the date area is 42 bytes. In any event, a field .S... Instruction Sequence Error - indicates a violation of one of the following sequence rules: 1. An IF instruction with an and/or link can only be followed by an IF instruction. Conversely, an IF instruction cannot immediately follow an IF instruction that does not have an and/or link. 2. An UNCONDITIONAL instruction can only be used to start a routine that immediately follows a routine started by an IF or OTHERWISE Instruction. 3. An OTHERWISE instruction can only be used to start a routine that immediately follows a routine started by an IF instruction. 4. IF, OTHERWISE, or UNCONDITIONAL instructions may not immediately precede or follow each other since only one type of conditional instruction may be used to start a routine. However, several IF 0 ________________________________________________________________________ -43- 1 BESTOP ________________________________________________________________________ instructions may appear in succession when they are properly linked. 5. A SUBROUTINE or TABLE may not be defined within a SUBROUTINE. However, a SUBROUTINE may contain a BRANCH to another subroutine as long as it does not result in a direct or indirect branch back to the SUBROUTINE containing the BRANCH. T..... Parameter Type Error (may occur in any parameter) - The specified parameter was not of a type that is recognized by the BESTOP program. The following types are permitted: 1. Operation codes and modifiers - single characters 2. Constants - enclosed in apostrophes. An apostrophe within a constant is represented by two successive apostrophes. 3. Field specifications of the form F.S.E or F.S where: F is a valid file code, S is one to four digits denoting the starting position of the field, and E is one to four digits denoting the ending position of the field. Parameters must be separated from each other by one or more blanks. D.__Record_Counts_And_File_Dumps + __ ______ ______ ___ ____ _____ Record counts for each file processed by the program are printed at the end of the run. These counts should be checked for consistency with the anticipated results of the run. The program also prints a dump of the first fifty records that were processed in the order in which they were read or written. The records are printed 100 characters to the line and are identified by file. Record lengths and consecutive record numbers are also shown on the listing. These dumps should be reviewed carefully to verify the processing performed by the program. - ________________________________________________________________________ -44- 1 BESTOP ________________________________________________________________________ E.__Test_Runs + __ ____ ____ Test runs may be performed to obtain any diagnostic messages that might be produced by the compilation of a program or to check the processing of a limited number of records from the input files(s). A program that contains diagnostic errors cannot be executed. If a diagnostic error is encountered, the run is terminated at the end of the compilation step. It is frequently advantageous to submit a short production run without testing since the program will either be executed or Bestop will issue diagnostic messages indicating why the run cannot be executed. Occasionally, it is useful to compile a program for diagnostic purposes without executing it even if there are no diagnostic errors. It is possible to do this by specifying a diagnostic run in the program parameters of the job control language. Short test runs can be executed on a portion of the input file(s) by including a halt procedure in the program. This procedure should count the number of passes through the object program and halt the run when a sufficient number of records have been processed. For example, a procedure that would limit the processing to 500 records from a single input file would be: + '1' S.1.3 I N S.1.3 G '500' H R - - - - - - - ________________________________________________________________________ -45- 1 BESTOP ________________________________________________________________________ VI.__APPENDIX_A_-_OS/370_OPERATING_INSTRUCTIONS + ___ ________ _ _ ______ _________ ____________ 0 A.__Job_Control_Language + __ ___ _______ ________ Job control language (JCL) provides information to the operating system on the files and other resources required for a job. It also identifies the user and provides necessary accounting information. B.__JOB_Statement + __ ___ _________ The JOB statement identifies the user, specifies his account number and establishes the work class of the job. The parameters of the JOB card are covered in the User's Guide. C.__EXEC_Statement + __ ____ _________ The EXEC statement calls the BESTOP compiler, passes program parameters, specifies core memory requirements and sets a time limit for the run. An EXEC statement is required for each BESTOP program that is to be run within a job. It is normally written in the following form: //step EXEC PGM=BESTOP,REGION=sizeK,PARM='parameters' where: step - is the name of the step within the job. It must begin with a letter and may not exceed 8 characters. size - is the memory requirement in thousands of bytes. This number must be followed by the letter "K." Bestop requires a minimum of 54K if tape or disk files are not used. Additional memory for tape and disk files is equal to approximately twice the sum of the tape or disk file block sizes. (See BLKSIZE in the DD statement.) parameters - are the program parameters required by the BESTOP compiler. They must be separated by commas and enclosed in apostrophes. The following parameters may be used: N Suppresses the Bestop program listing I=(R/1-6) Specifies the file code of the input file in runs with a single input file. T=(1/2) Specifies the run type in matched file runs. ________________________________________________________________________ -46- 1 BESTOP ________________________________________________________________________ A=(R/1-6) Specifies the A file in a matched file run. B=(R/1-6) Specifies the B file in a matched file run. D Specifies a diagnostic run. C=number Specifies the number of records to be dumped on DDN=FILEDUMP, the default is fifty. Example: Exec Statement //STEP1 EXEC PGM=BESTOP,REGION=420K,PARM='T=1,A=1,B=2' D.__STEPLIB_Card + __ _______ ____ The STEPLIB card is required. It identifies the library on which the BESTOP compiler is located. //STEPLIB DD DISP=SHR,DSN=FEA.LINKLIB E.__DD_Statements + __ __ __________ The DD Statement is used to identify the files to be processed in a step, to designate them as input or output files and to specify the disposition of the files at the end of the run. They are also used to specify the logical record length and block size for output files. Consult the instalations User's Guide and various manuals for details. Example: Job Control Language To transfer a deck of cards to a temporary file on disk that is to be used in a later step in the job. //STEPA EXEC PGM=BESTOP,REGION=240K,PARM='I=R' //STEPLIB DD DISP=SHR,DSN=FEA.LINKLIB //FIELDUMP DD SYSOUT=A //LISTING DD SYSOUT=A //FILE1 DD UNIT=SYSDA,DISP=(NEW,PASS),SPACE=(CYL,(5,5)), // DCB=(LRECL=80,BLKSIZE=6400),DSN=&&CARDS //PROGRAM DD * M R.1.80 1.1.80 W 1 //READER DD * ________________________________________________________________________ -47- 1 BESTOP ________________________________________________________________________ . . . data cards . . . To read and process a tape file to produce a new tape file. //PROCESS EXEC PGM=BESTOP,REGION=190K,PARM='I=1' //STEPLIB DD DISP=SHR,DSN=FEA.LINKLIB //FILEDUMP DD SYSOUT=A //LISTING DD SYSOUT=A //FILE1 DD DSN=CNaaaa.uuu.MY.DATA,DISP=OLD //FILE2 DD DSN=CNaaaa.uuu.COPY.DATA,DISP=(,CATLG), // DCB=(LRECL=80,BLKSIZE=6160,RECFM=FB), // UNIT=DASD,SPACE=(TRK,(10,10),RLSE) //PROGRAM DD * . . program cards . . F.__Completion_Codes + __ __________ _____ The following completion codes may be encountered in BESTOP runs. S000 Normal end of run S004 run ended by halt run instruction. S008 Diagnostic run S00C Run ended by HALT JOB instruction S322 Execution of the job step took longer than the time allowed by the TIME parameter. S722 Maximum number of lines exceeded. S80A The program required more memory than specified in the REGION parameter. S813 The dsname specified in a DD statement does not agree with the dsname in the file header label. 0 ________________________________________________________________________ -48- 1 BESTOP ________________________________________________________________________ G.__External_Tables + __ ________ ______ Frequently it may be more convenient to code a Bestop table and save it into a dataset that may be referenced by the Bestop program. This may be accomplished by coding the table entries (arguments and results) on a records and saving these records into a card image file .The table is then referenced via a special DD statement identifying the external table. Example: External Table //STEP1 EXEC PGM=BESTOP,REGION=240K,PARM='I=R' //STEPLIB DD DISP=SHR,DSN=FEA.LINKLIB //FIELDUMP DD SYSOUT=A //LISTING DD SYSOUT=A //TABLEQ DD DISP=OLD,DSN=CNaaaa.PRJ.BESTOP.TABLES(TABQ) //FILE1 DD UNIT=SYSDA,DISP=(NEW,PASS),SPACE=(CYL,(5,5)), // DCB=(LRECL=120,BLKSIZE=6000),DSN=&&CARDS //PROGRAM DD * ****** ADD COUNTY NAMES TO THE FILE ***** M R.1.80 1.1.80 L Q E W 1 T Q R.1.6 1.101.120 * COUNTY NAME LOOKUP $ //READER DD * . . . data cards . Notes: The "TABLEQ" JCL statement establishes the linkage between the exteranl table and the table definition in the program. The record length of the external must be 80. Therefore the sum of the lengths of the argument and result cannot exceed 80. The "$" after the table definition statement indicates that this is a external table. ________________________________________________________________________ -49- 1 BESTOP ________________________________________________________________________ VII.__APPENDIX_B_-_MAXIMUM_FIELD_SIZES + ____ ________ _ _ _______ _____ _____ 0 The widths of the fields or constants in the following instructions are limited to the specified number of characters. IF (Character Field Comparison 256 IF (Numeric Field Comparison 16 IF (Control Break) 256 MOVE 4096 EDIT 16 CLEAR 4096 ADD 16 SUBTRACT 16 MULTIPLY Multiplicand 16 Multiplier 15 Product + Rounding 16 DIVIDE Dividend 16 Divisor 15 Quotient (extended) 14 KEYS 256 - - - - - - - - ________________________________________________________________________ -50- 1 BESTOP ________________________________________________________________________ VIII.__APPENDIX_C_-_EIA_IMPLEMENTATIONS_OF_BESTOP + _____ ________ _ _ ___ _______________ __ ______ 0 A.__BESTOP50,_BESTOPVL,_BEST400 + __ _________ _________ _______ These are the original versions of BESTOP avalibale at EIA. Basically they are all the same. In the BEST400 version, 400K of work area is allocated in order that the user may write larger programs or tables. B.__SUPERB + __ ______ SUPERB is a enhanced version of BESTOP the allows the user to call this program from a higher level language like PL/1 or Cobol. Furthermore, only columns 1 thur 72 of the source program are scanned, and columns 73 thru 80 are ignored. This means the user may enter "RUN FETCH" instead of "RUN FET UNN" in Superwylbur. In addition, the source program gets listed in the SYSPRINT file rather than the LISTING file. Also file counts are displayed in the SYSPRINT file. C.__BESTOP + __ ______ BESTOP is actually a PL/1 program that calls SUPERB. It offers several interesting features. The user may code instructions to copy source code from a library into his/her program. Another feature of this program is that more than one instruction can be coded on one line, provided that the instructions are seperated by a semicolon. When the instructions are listed during exection, they will be listed on seperate lines. As the code is being copied, it may simultaneously be modified. Another interesting feature is that BESTOP has several "canned" program imbedded within it. Most notably is a update program. All the user needs to code is the program invocation and suitable parameters. This update program can handle virtually any simple sequential file structure. Other canned routines include a sequence checking routine, a dump and a file comparison routine. Example //UPD EXEC PGM=BESTOP,REGION=600K,PARM='T=1,A=1,B=3' //STEPLIB DD DISP=SHR,DSN=FEA.LINKLIB //SYSPRINT DD SYSOUT=A //LISTING DD SYSOUT=V,FLASH=OUO //FILE1 DD DISP=(OLD,DELETE),DSN=&&UPD //FILE2 DD DSN=&&NEWM,UNIT=SYSDA, // DISP=(NEW,PASS),SPACE=(CYL,(1,1),RLSE), // DCB=(RECFM=FB,LRECL=80,BLKSIZE=6160) //FILE3 DD DISP=(OLD,DELETE),DSN=&&MSTR //PROGRAM DD * @UPDATE K='1.1.22 3.1.22 1.30.36 3.30.36', + T='23',S='37',E='80',L='80' ________________________________________________________________________ -51- 1 BESTOP ________________________________________________________________________ Notes: FILE1 is the transaction file. FILE3 is the old master file. FILE2 is the updated master file. The key fields are the first 22 positions in each file. Each file must therefore be sorted on these positions. The transaction code is in position 23 of the transaction file. Valid codes and there function are as follows: A,I - add/insert a record into the file C,R - change/revise a record D - delete a record U - add a record if the transaction key is less than the master key, otherwise change a record if the keys match. The plus sign indicates that this instruction is continued. "S" indicates the start of the data. "E" indicates the end of the data, and "L" shows the record length. If E=L, then E may by omitted. Revisions are performed in the data area only. This updated program assumes no prior knowledge of the demarcation of data fields. Revisions are performed on a character by character basis according to the following rules: 1. If a character on the transaction record is blank,then the corresponding character on the master file record will remain unchanged. 2. If the character on the transaction record is not blank, then this character replaces the corresponding character on the master file record. 3. The exception to the previous rule is that if the transaction record has the value of the "BLANK" variable (default is "_"), then the corresponding character on the master file record becomes blank. 0 ________________________________________________________________________ -52- 1 BESTOP ________________________________________________________________________ Only the first 130 characters of the transaction record will be listed. The type of transaction is indicated in column one of the listing as follows: "+" - this record has been added to the file "-" - this recods has been deleted from the file " " - this is a revision/change transaction record ">" - this is the original master record to be changed "<" - this id the changed master file record "*" - this transaction record has a processing error (i.e. a matching record exist if an insert was attempted, or no matching record exists if a delete or change was attempted) Example Obtain the documentation for the various canned programs @HELP HELP Get the description of the syntax for the sequence checking program @HELP SEQCHK - - - - - ________________________________________________________________________ -53- 1 BESTOP ________________________________________________________________________ Example Copy source code into a Bestop program prior to actual program execution. //DUMP EXEC PGM=BESTOP,REGION=600K,PARM='I=1' //STEPLIB DD DISP=SHR,DSN=FEA.LINKLIB //SYSPRINT DD SYSOUT=A //LISTING DD SYSOUT=A //FILE1 DD DISP=OLD,DSN=CNaaaa.uuu.MASTER.FILE //MACROS DD DISP=SHR,DSN=CNaaaa.uuu.BESTOP.SOURCE.LIB //PROGRAM DD * * LIST STATES ALABAMA & ALASKA FROM THE MASTER FILE * ALSO LIST STATE AND COUNTY NAMES * 1.3 = STATE CODE, 1.6 = STATE & COUNTY CODE I M 1.1.6 E '010,020' M 1.1.80 L.1.80 L S E * LOOKUP STATE NAME L C E * LOOKUP CNTY NAME W L 2 T S 1.1.3 L.81.100 * STATE TABLE &STATES SEL=(010), SEL=(020) T C 1.1.6 L.101.120 * COUNTY NAMES &COUNTIES SEL=(010), SEL=(020) Notes: The file defined by the DDName=MACROS must be a partitioned dataset. "STATES" and "COUNTIES" are members of the PDS. To include data from a member into the program, code an ampersand "&" in column 1 followed by the member name. The included data may be qualified and/or modified during the copy operation. (For a more complete description of this mechanism, reference the documentation for the MACROS program written by Hans Becker (202-252-6874)). - - 0 ________________________________________________________________________ -54-